

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Search APIs &mdash; Open Legislation 2.0-alpha documentation</title>
  

  
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  

  
        <link rel="index" title="Index"
              href="genindex.html"/>
        <link rel="search" title="Search" href="search.html"/>
    <link rel="top" title="Open Legislation 2.0-alpha documentation" href="index.html"/>
        <link rel="prev" title="Aggregate Updates API" href="agg_updates.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="reference.html" class="icon icon-home"> Open Legislation
          

          
          </a>

          
            
            
              <div class="version">
                2.0
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html"><strong>Open Legislation v2.0 API Docs</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="bills.html"><strong>Bills and Resolutions API</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="calendars.html"><strong>Senate Calendar API</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="agendas.html"><strong>Senate Agenda API</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="committees.html"><strong>Senate Committee API</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="laws.html"><strong>NYS Laws API</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="transcripts_floor.html"><strong>Senate Floor Transcripts API</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="transcripts_ph.html"><strong>Public Hearing Transcripts API</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="members.html"><strong>Senate Members API</strong></a></li>
<li class="toctree-l1"><a class="reference internal" href="agg_updates.html"><strong>Aggregate Updates API</strong></a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#"><strong>Search APIs</strong></a><ul>
<li class="toctree-l2"><a class="reference internal" href="#term">term</a></li>
<li class="toctree-l2"><a class="reference internal" href="#sort">sort</a></li>
<li class="toctree-l2"><a class="reference internal" href="#search-response">Search Response</a></li>
</ul>
</li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="reference.html">Open Legislation</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="reference.html">Docs</a> &raquo;</li>
        
      <li><strong>Search APIs</strong></li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/search_api.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="search-apis">
<h1><strong>Search APIs</strong><a class="headerlink" href="#search-apis" title="Permalink to this headline">¶</a></h1>
<p>Most of the Open Legislation data APIs include search functionality.  We built our search layer using elasticsearch
and we aim to provide as much elasticsearch functionality as possible through the APIs.</p>
<p>Every search layer API will have a required request parameter &#8220;term&#8221; and an optional request param &#8220;sort&#8221;.</p>
<div class="section" id="term">
<span id="search-term"></span><h2>term<a class="headerlink" href="#term" title="Permalink to this headline">¶</a></h2>
<p>The term parameter takes in an <a class="reference external" href="https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#_field_names">elasticsearch query string</a>.</p>
<p>The simplest way to search is to send a general search term.
For example, to search for legislation pertaining to apples, the following query will do the job.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>/api/3/bills/search?term=apples
</pre></div>
</div>
<p>In addition to a simple search term, there are a number of advanced features available.  Our search index is generated
with data in the same JSON format as the API responses, so any response field that is nested under &#8220;result&#8221; is fair game
for search.  Going back to the previous example, a number of resolutions appear in the results for the apples search query.
Looking back at the <a class="reference internal" href="bills.html#bill-response"><span class="std std-ref">bill response</span></a>, we see that resolutions are designated by the &#8220;resolution&#8221; boolean under &#8220;billType&#8221;.
In order to filter resolutions out of the search results, a field query can be chained to the original query using &#8220;AND&#8221;.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>/api/3/bills/search?term=apples%20AND%20billType.resolution:false
</pre></div>
</div>
<p>For a full enumeration of query features see the <a class="reference external" href="https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#_field_names">elasticsearch query string</a> syntax.</p>
</div>
<div class="section" id="sort">
<span id="search-sort"></span><h2>sort<a class="headerlink" href="#sort" title="Permalink to this headline">¶</a></h2>
<p>Searches can be sorted by any number valid response fields.  This is accomplished using the sort request parameter,
which takes a comma separated string of response fields, each designated with a sort order (&#8220;ASC&#8221; or &#8220;DESC&#8221;) separated
from the field with a colon.</p>
<p>For example, to get the 2013 governor&#8217;s program bills in canonical order:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>/api/3/bills/2013/search?term=programInfo.name:Governor%20AND%20_missing_:substitutedBy
                        &amp;sort=programInfo.sequenceNo:ASC
</pre></div>
</div>
<p>Or, you may want to order them by their status and action date:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>/api/3/bills/2013/search?term=programInfo.name:Governor%20AND%20_missing_:substitutedBy
                        &amp;sort=status.statusType:ASC,status.actionDate:DESC
</pre></div>
</div>
</div>
<div class="section" id="search-response">
<h2>Search Response<a class="headerlink" href="#search-response" title="Permalink to this headline">¶</a></h2>
<div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="s2">&quot;success&quot;</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
  <span class="s2">&quot;message&quot;</span><span class="o">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
  <span class="s2">&quot;responseType&quot;</span><span class="o">:</span> <span class="s2">&quot;search-results list&quot;</span><span class="p">,</span>
  <span class="s2">&quot;total&quot;</span><span class="o">:</span> <span class="mi">7</span><span class="p">,</span>
  <span class="s2">&quot;offsetStart&quot;</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
  <span class="s2">&quot;offsetEnd&quot;</span><span class="o">:</span> <span class="mi">7</span><span class="p">,</span>
  <span class="s2">&quot;limit&quot;</span><span class="o">:</span> <span class="mi">10</span><span class="p">,</span>
  <span class="s2">&quot;result&quot;</span><span class="o">:</span> <span class="p">{</span>
    <span class="s2">&quot;items&quot;</span><span class="o">:</span> <span class="p">[</span>
      <span class="p">{</span>
        <span class="s2">&quot;result&quot;</span><span class="o">:</span> <span class="p">{</span> <span class="p">...</span> <span class="p">},</span>            <span class="c1">// A search result</span>
        <span class="s2">&quot;rank&quot;</span><span class="o">:</span> <span class="mf">0.3587615191936493</span>    <span class="c1">// The ranking of the search result</span>
      <span class="p">},</span>
      <span class="p">...</span>                           <span class="c1">// More search results</span>
    <span class="p">],</span>
    <span class="s2">&quot;size&quot;</span><span class="o">:</span> <span class="mi">7</span>
  <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
      
        <a href="agg_updates.html" class="btn btn-neutral" title="Aggregate Updates API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2014, NY State Senate Technology Services.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'2.0-alpha',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: '.txt'
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>